adji.1
1.TH ADJI 1 adji\-VERSION
2.
3.SH NAME
4adji \- Adji's a Decisive and Joyful Internet browser
5.
6.SH SYNOPSIS
7.B adji
8.RB [ \-I " [" \- ]]
9.IR "" [ URI ...]
10.IR "" [ FILE ...]
11.
12.SH DESCRIPTION
13.B adji
14is a simple, decisive and distraction free web browser using GTK+ 3,
15GLib and WebKit2GTK+. This web browser takes inspiration from other web
16browsers like
17.BR surf (1),
18.BR lariza (1)
19and
20.BR vimb (1).
21.
22.SH OPTIONS
23Along with the standard arguments for GTK+ 3 (see
24.BR gtk-options (7)),
25.B adji
26is equipped with the following options:
27.TP
28.B -I
29Implements an independent instance without any IPC configuration.
30.P
31If no URIs are provided, the value of the enviornment variable
32.B ADJI_HOME_URI
33will be opened, which defaults to \(lqabout:blank\(rq. If the first URI is '-',
34.B adji
35will only read and interpret
36.B STDIN
37as HTML content. However, the content will only be processed when running as an
38independent instance. Content from
39.B STDIN
40won't survive a page reload either. If that is needed, temporary files should
41instead be utilized. Otherwise, any number of URIs may follow these options.
42.
43.SH ENVIRONMENT
44.B adji
45recognizes the following environment variables, in addition to the standard
46variables of GTK+ 3:
47.P
48.TP
49.B
50ADJI_ACCEPTED_LANGUAGES
51When sending an HTTP request, WebKit populates the \(lqAccepted-Language\(rq
52header based on the provided list of languages, which can be comma-separated
53(e.g. \(lqen_US,en_AU\(rq). If no languages are specified, WebKit will use
54.B en_US
55as the default.
56.TP
57.B
58ADJI_CHARSET
59The character encoding that is automatically assumed when interpreting content
60that does not specify a particular charset. Defaults to \(lqUTF-8\(rq.
61.TP
62.B
63ADJI_COOKIE_FILE
64By providing a path to a cookie file,
65.B adji
66will provide a method of sharing cookies between sessions and instances.
67.TP
68.B
69ADJI_DEFAULT_FONT
70Provides a method for specifying the default font inside the web view of
71.BR adji .
72If no default font is specified, WebKit will use
73.B sans-serif
74as the default.
75.TP
76.B
77ADJI_DEFAULT_FONT_SIZE
78Provides a method for specifying the default font size inside the web view of
79.BR adji .
80If no default font size is specified, WebKit will use
81.B 16
82as the default.
83.TP
84.B
85ADJI_DISABLE_AUTO_LOAD_IMAGES
86For a faster, or perhaps a more secure way of browsing the web, setting this
87variable provides a method of preventing images from loading automatically.
88.TP
89.B
90ADJI_DISABLE_JAVASCRIPT
91For a faster, or perhaps a more secure way of browsing the web, setting this
92variable provides a method of preventing JavaScript from loading. However,
93executing user scripts is still possible, as only JavaScript from markup is
94removed.
95.TP
96.B
97ADJI_DOWNLOAD_DIR
98This variable allows you to specify the directory to where all downloads are
99stored according to your preference. By default all downloads are stored at
100.BR /var/tmp .
101.TP
102.B
103ADJI_ENABLE_CONSOLE_TO_STDOUT
104Output that is printed to the web view console can be copied to
105.B STDOUT
106setting this variable.
107.TP
108.B
109ADJI_ENABLE_SMOOTH_SCROLLING
110By default
111.B adji
112disables the janky and annoying \(lqsmooth scrolling\(rq. If you for some
113reason like it, setting this variable will enable it.
114.TP
115.B
116ADJI_EXTERNAL_HANDLER_KEYS
117A list of keys that, when pressed, executes the external handler script located
118at
119.I ~/.config/adji/exthandler
120while at the same time forwarding the pressed key to handler script. This
121enables the user to define custom keys that is referred to custom functions in
122the handler script. The list of keys should be comma-separated
123(e.g. \(lqA,y,P\(rq).
124.TP
125.B
126ADJI_FIFO_NAME
127.B adji
128implements IPC configurations using named pipes in the file system. According
129to XDG standards, the files for these named pipes are stored as
130.IR /var/run/user/$UID/adji_$ADJI_FIFO_NAME.fifo .
131
132The
133.B $UID
134refers to the id of the user running
135.BR adji .
136.B $ADJI_FIFO_NAME
137refers to the value of this variable, which defaults to
138.BR default .
139By specifying this variable, parallel IPC configurations can be used. Be sure
140to also specify the $ADJI_STATE_FILE accordingly. If you do not, the IPC
141instances will conflict and overwrite the states of each other.
142.TP
143.B
144ADJI_HISTORY_FILE
145When set,
146.B adji
147will store each visited URI to the file specified.
148.TP
149.B
150ADJI_HOME_URI
151The URI that will be opened in new tabs if nothing else is specified. Defaults
152to
153.BR "about:blank" .
154.TP
155.B
156ADJI_MONOSPACE_FONT
157Provides a method for specifying the monospace font inside the web view of
158.BR adji .
159If no monospace font is specified, WebKit will use
160.B monospace
161as the default.
162.TP
163.B
164ADJI_PROXY_IGNORE
165When specifying a proxy URI,
166.B adji
167will send every HTTP requests through that URI. To exclude traffic to certain
168hosts from being sent through the specified proxy URI, this variable can be
169used to provide a comma-separated list of hosts to be ignored
170(e.g. \(lq127.0.0.1,noxz.tech\(rq).
171.TP
172.B
173ADJI_PROXY_URI
174By specifying a proxy URI,
175.B adji
176will send every HTTP requests through that URI. As an example a socks proxy for
177tor can be specified in this way \(lqsocks://127.0.0.1:9050\(rq.
178.TP
179.B
180ADJI_SANS_SERIF_FONT
181Provides a method for specifying the sans-serif font inside the web view of
182.BR adji .
183If no sans-serif font is specified, WebKit will use
184.B sans-serif
185as the default.
186.TP
187.B
188ADJI_SERIF_FONT
189Provides a method for specifying the serif font inside the web view of
190.BR adji .
191If no serif font is specified, WebKit will use
192.B serif
193as the default.
194.TP
195.B
196ADJI_SE_URI_FORMAT
197If an entry cannot be resolved as either a URI or a file path, a web search
198will be performed. To define the method of perforating this web search, a
199format can be utilized in the following manner, using
200.I http://ddg.gg
201as an example: \(lqhttps://ddg.gg?q=%s\(rq.
202One, and only one, string reference
203.BR "" ( %s )
204must be specified. The default value is
205.BR "https://ddg.gg?q=%s" .
206.TP
207.B
208ADJI_STATE_FILE
209By specifying a path to a state file,
210.B adji
211will save the state of open tabs for next time the program is run. Each time a
212tab is moved, updated or otherwise changed, the state of open tabs will be
213saved as a list of URIs. It is important to avoid using the same state file for
214multiple IPC configurations, as they will conflict and overwrite each other.
215.TP
216.B
217ADJI_VERBOSE
218If set, this feature is employed by
219.B we_redirect.so
220to verbosely output to
221.B STDERR
222which redirections are being.
223.TP
224.B
225ADJI_USER_AGENT
226By default,
227.B adji
228uses WebKit's default value for the user agent string. This variable can be
229utilized to specify an alternative user agent to the default one.
230.TP
231.B
232ADJI_ZOOM_LEVEL
233This variable can be utilized to set the zoom level of WebKit's viewports. The
234default value is
235.BR 1.0 .
236.TP
237.B
238ADJI_XDG_SCHEMES
239Enables the user to define a list of schemes that should be redirected to the
240.B xdg-open
241program. The list of schemes should be comma-separated
242(e.g. \(lqmailto,doi\(rq). If no schemes are specified, the default behaviour
243is to not redirect any schemes to the
244.B xdg-open
245program. Custom user-defined schemes can also be used, as the user can define
246any sort of scheme except the ones already handled by
247.BR adji .
248.
249.SH FILES
250These paths will be constructed using XDG variables.
251.TP
252.I ~/.config/adji/redirect
253Redirect rules used by
254.BR we_redirect.so .
255See the
256.B "WEB EXTENSION"
257section.
258.TP
259.I ~/.config/adji/exthandler
260.B adji
261has a built-in mechanism for externally handling URIs. You can use the file
262specified by the path to define how these URIs should be handled in a
263customized manner. A system call passes the URI as the first parameter.
264.TP
265.I ~/.config/adji/scripts
266Directory to store user scripts (JavaScript).
267.TP
268.I ~/.config/adji/styles
269Directory to store user style sheets (CSS).
270.TP
271.I ~/.config/adji/web_extensions
272Directory where WebKit will search for web extensions.
273.TP
274.I ~/.cache/adji
275.TQ
276.I ~/.cache/webkitgtk
277.TQ
278.I ~/.local/share/webkitgtk
279WebKitGTK will store its caches and local storage data in these directories.
280It is recommended to periodically clean these directories or mount them as
281some sort of volatile storage.
282.
283.SH USAGE
284.
285.SS Entry
286Entry refers to the entry/location/command bar at the bottom of the window.
287.TP
288.B Mod1\-h
289Navigate the caret to the left in the entry.
290.TP
291.B Mod1\-l
292Navigate the caret to the right in the entry.
293.TP
294.B Enter/Return
295The entered command or URI is resolved as appropriate. If no resolution is
296found, the entry is reverted back to its original value.
297.TB
298.B Escape
299The entry is reverted back to its original value.
300.
301.SS Tab bar
302.TP
303.B Button1
304When a tab is clicked, the corresponding pair of web view and entry will be
305made visible
306.TP
307.B Button2
308Clicking on a tab using the scroll wheel will close the pair of view and entry
309represented by that tab
310.TP
311.B Scroll wheel
312While hovering over the tab bar, scrolling the scroll wheel will allow you to
313move through tabs in the same direction as your scroll.
314.
315.SS Download bar
316The download bar remains hidden until a download is initiated. As the download
317progresses, the progress is shown and updated. Each download is represented by
318a button that can be clicked. During an active download, clicking the button
319with the middle or right mouse button will abort the download and remove the
320button. Once the download is complete, left-clicking the button will open the
321downloaded file using 'xdg-open,' while clicking the button with the middle
322or right mouse button will simply remove it.
323.
324.SS Web view
325.TP
326.B Escape
327Stops the web rendering.
328.TP
329.B Button2
330Opens a hovered URI in a new tab.
331.TP
332.B Button8
333Go back in history.
334.TP
335.B Button9
336Go forward in history.
337.TP
338.B Mod1\-[Scroll Wheel]
339The zoom level of the current web view can be adjusted by scrolling while
340holding down the
341.B Mod1
342key.
343.
344.SS Global keyboard commands
345.TP
346.B Mod1\-Ctrl\-Shift\-j
347Move the current tab to the left (further down in the stack) within the tab
348bar.
349.TP
350.B Mod1\-Ctrl\-Shift\-K
351Move the current tab to the right (further up in the stack) within the tab
352bar.
353.TP
354.B Mod1\-Ctrl\-j
355Switch to the previous tab (the one to the left of the current one).
356.TP
357.B Mod1\-Ctrl\-k
358Switch to the next tab (the one to the right of the current one).
359.TP
360.B Mod1\-[1..n]
361Switch to the nth tab.
362.TP
363.B Mod1\-q
364Close the current tab.
365.TP
366.B Mod1\-w
367Go the specified home page.
368.TP
369.B Mod1\-t
370Open the specified home page within a new tab.
371.TP
372.B Mod1\-r
373Reload the page, bypassing the cache.
374.TP
375.B Mod1\-o
376Focus the entry bar for input.
377.TP
378.B Mod1\-/
379Initiate an in-page search.
380.TP
381.B Mod1\-n
382Perform a forward search within the context of the in-page search.
383.TP
384.B Mod1\-Shift\-n
385Perform a backwards search within the context of the in-page search.
386.TP
387.B Mod1\-b
388Toggle the visibility of the tab bar.
389.TP
390.B Mod1\-Shift\-h
391Go back in history.
392.TP
393.B Mod1\-Shift\-l
394Go forward in history.
395.TP
396.B Mod1\-s
397Toggle JavaScript functionality on or off.
398.TP
399.B Mod1\-c
400Toggle the TLS error policy between fail or ignore.
401.TP
402.B Mod1\-h
403Move/scroll towards the left on the page.
404.TP
405.B Mod1\-l
406Move/scroll towards the right on the page.
407.TP
408.B Mod1\-j
409Move/scroll towards the bottom of the page.
410.TP
411.B Mod1\-k
412Move/scroll towards the top of the page.
413.TP
414.B Mod1\-Shift\-g
415Go to the bottom of the page.
416.TP
417.B Mod1\-g
418Go to the top of the page.
419.TP
420.B Mod1\-p
421Open the print dialog.
422.
423.SS Entry commands
424Commands can be executed from the entry using a proceeding \(lq:\(rq.
425.B adji
426accepts two types of commands.
427.TP
428.B q
429If applicable, the program saves its state before quitting.
430.TP
431.B /
432To initiate an in-page search for a specific phrase, such as \(lqbanana\(rq,
433you would enter the succeeding phrase in the format of
434.BR :/banana .
435.
436.SS "User scripts"
437Upon successful loading of a page, the directory
438.I "~/.config/adji/scripts"
439is scanned, and every file with the \(lq.js\(rq extension is executed as a
440JavaScript file within the context of the loaded page.
441.
442.SS "User styles"
443Upon successful loading of a page, the directory
444.I "~/.config/adji/styles"
445is scanned, and every file with the \(lq.css\(rq extension is injected as a
446style sheet within the context of the loaded page. These style sheets can be
447utilized to customize the appearance of web pages according to your
448preferences.
449.
450.SH WEB EXTENSION
451.TP
452.B we_redirect.so
453To specify redirect rules in the redirect file, you should use the following
454format:
455.BR "/pattern/destination/" .
456Each rule should be written on a single line,
457and an arbitrary separator should be used to initialize each rule.
458This separator can be any character except for the \(lq#\(rq symbol,
459which is used for line comments. The
460.B pattern
461can be any regular expression pattern that matches a URI request. The
462.B destination
463can be left empty, or it can contain a replacement pattern that references
464regex groups from the pattern. If the destination is empty, the request will be
465terminated and act as a URI block.
466
467Regular expressions in terms of syntax and semantics are akin to Perl regular
468expressions.
469.
470.SH EXAMPLES
471.TP
472.B "adji -I"
473This command launches an independent
474.I adji
475instance without any IPC configuration. It will not load or save any states.
476However, if certain environment variables like
477.B ADJI_HISTORY_FILE
478and
479.B ADJI_COOKIE_FILE
480are defined, this instance will use them. Therefore, it cannot be considered
481completely isolated.
482
483To make such an instance more isolated the variables
484.BR ADJI_HISTORY_FILE ,
485.BR ADJI_COOKIE_FILE ,
486.BR XDG_CACHE_HOME ,
487and
488.BR XDG_DATA_HOME
489should be set to the value \(lq/dev/null\(rq before executing the command.
490.TP
491.B "ADJI_PROXY_URI=socks://127.0.0.1:9050 adji -I"
492This command launches an independent
493.I adji
494instance without any IPC configuration. It routes every HTTP request through a
495designated proxy URI, specifically a tor socks proxy in this case. It will not
496load or save any states.
497
498However, to enhance privacy and isolation of this instance, measures must be
499taken to prevent data leakage through cookies or other sources. Additionally,
500consider using a more privacy-focused web browser.
501.
502.SH KNOWN ISSUES
503Double-clicking on a tab grabs the focus and prevents global key commands from
504functioning. This issue could be addressed by focusing the web view upon tab
505click events. However, as it is a minor problem and only present in a mouse
506workflow, such a solution has not been implemented.
507.
508.SH AUTHOR
509Chris Noxz <chris@noxz.tech>
510.
511.SH COPYRIGHT
512Copyright \(co 2023 Chris Noxz.
513.P
514License: GPLv3+
515.P
516GNU GPL version 3 or later
517<https://www.gnu.org/licenses/licenses.html>.
518.P
519This is free software: you are free to change and redistribute it.
520There is NO WARRANTY, to the extent permitted by law.
